// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IWorkProvider.cs" company="AzureContrib (Open source library http://azurecontrib.codeplex.com)">
//   Microsoft Public License (Ms-PL)
// </copyright>
// <summary>
//   A service that schedules and hands out <see cref="IWorkItem" />.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;

using AzureContrib.WindowsAzure.ServiceRuntime.ServiceLocation;

namespace AzureContrib.WindowsAzure.WorkServices
{
	/// <summary>
	/// A service that schedules and hands out <see cref="IWorkItem"/>.
	/// </summary>
	public interface IWorkProvider : IBuilderUser
	{
		/// <summary>
		/// Get a <see cref="IWorkItem"/> to work on. Default <see cref="WorkType"/> is <see cref="WorkType.Run"/>.
		/// </summary>
		/// <returns>Always returns a live <see cref="IWorkItem"/> instance.</returns>
		/// <remarks>Will execute <see cref="IWorkItem.HasWork"/> on each item until one is true. This one is returned.</remarks>
		[SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", Justification = "An underlying calculation to find the next piece of work needs to be performed. This is best communicted thorugh a method signature.")]
		IWork GetWork();

		/// <summary>
		/// Get all work of a speciffic type
		/// </summary>
		/// <param name="workType">The type of work.</param>
		/// <returns>All <see cref="IWork"/> found.</returns>
		/// <remarks>Default behavior is to not return work that does not <see cref="IWorkItem.HasWork"/>.</remarks>
		/// <remarks>Default is to not return work that is not pending. <seealso cref="GetAllWork(WorkType,bool)"/></remarks>
		IEnumerable<IWork> GetAllWork(WorkType workType);

		/// <summary>
		/// Get all work of a speciffic type
		/// </summary>
		/// <param name="workType">The type of work.</param>
		/// <param name="includeWorksNotPending">Work that does not <see cref="IWorkItem.HasWork"/> are normally not returned.</param>
		/// <returns>All <see cref="IWork"/> found.</returns>
		/// <remarks>Default behavior is to not return work that does not <see cref="IWorkItem.HasWork"/>.</remarks>
		IEnumerable<IWork> GetAllWork(WorkType workType, bool includeWorksNotPending);
	}
}